package com.smart.community.property.service;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;
import java.util.Map;

import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.commons.result.PageResult;
import com.smart.community.property.dto.SanitationFeeEditDTO;
import com.smart.community.property.entity.SanitationFee;
import com.smart.community.property.vo.SanitationFeeVO;

/**
 * 卫生费服务接口
 * 
 * 严格按照《Java后端SpringBoot代码开发规范.md》Service规范：
 * - 生产环境标准：移除throws Exception声明，实现优雅降级
 * - 缓存策略：查询方法使用@Cacheable，更新方法使用@CacheEvict
 * - 性能监控：所有方法包含详细的性能指标记录
 * - 异常处理：统一异常处理机制，返回默认值而不是抛出异常
 * - 参数验证：完善的参数验证机制
 * - 工具方法：遵循单一职责、可复用性、错误处理、性能优化原则
 * 
 * @author Wu.Liang
 * @since 2024-12-21
 * @version 3.0.0
 */
public interface ISanitationFeeService extends IService<SanitationFee> {
    
    /**
     * 分页查询卫生费账单（返回VO对象，包含房户号、社区名、楼栋名、单元名等信息）
     * 
     * @param current 当前页
     * @param size 每页大小
     * @param communityId 社区ID
     * @param paymentStatus 支付状态
     * @param billingPeriod 计费周期
     * @param buildingId 楼栋ID
     * @param unitId 单元ID
     * @param householdId 房户ID
     * @param householdIds 房户ID列表
     * @return 分页结果，异常时返回空分页结果
     */
    PageResult<SanitationFeeVO> getSanitationFeePage(Integer current, Integer size,
                                                     Long communityId, String paymentStatus,
                                                     String billingPeriod, Long buildingId,
                                                     Long unitId, Long householdId, List<Long> householdIds);
    
    /**
     * 根据ID获取卫生费详情（返回VO对象）
     * @param id 卫生费ID
     * @return 卫生费详情，异常时返回null
     */
    SanitationFeeVO getSanitationFeeDetail(Long id);
    
    /**
     * 编辑卫生费（只允许编辑费用金额、缴费状态，到期日期不允许修改）
     * @param id 卫生费ID
     * @param dto 编辑数据
     * @return 是否编辑成功，异常时返回false
     */
    boolean updateSanitationFee(Long id, SanitationFeeEditDTO dto);
    
    /**
     * 根据用户ID查询未缴费卫生费账单
     * @param userId 用户ID
     * @return 未缴费账单列表，异常时返回空列表
     */
    List<SanitationFee> getUnpaidSanitationFeesByUserId(Long userId);
    
    /**
     * 卫生费缴费
     * @param billId 账单ID
     * @param paymentAmount 支付金额
     * @param paymentMethod 支付方式
     * @return 是否缴费成功，异常时返回false
     */
    boolean paySanitationFee(Long billId, BigDecimal paymentAmount, String paymentMethod);
    
    /**
     * 生成卫生费账单
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param perPersonFee 人均费用
     * @return 生成的账单数量，异常时返回0
     */
    int generateSanitationFee(Long communityId, LocalDate billingMonth, BigDecimal perPersonFee);
    
    /**
     * 生成卫生费账单（支持到期日期）
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param perPersonFee 人均费用
     * @param dueDate 到期日期
     * @return 生成的账单数量，异常时返回0
     */
    int generateSanitationFee(Long communityId, LocalDate billingMonth, BigDecimal perPersonFee, LocalDate dueDate);
    

    
    /**
     * 批量生成卫生费账单
     * @param communityIds 社区ID列表
     * @param billingMonth 计费月份
     * @param perPersonFee 人均费用
     * @return 各社区生成结果，异常时返回空Map
     */
    Map<String, Integer> batchGenerateSanitationFee(List<Long> communityIds,
                                                    LocalDate billingMonth,
                                                    BigDecimal perPersonFee);
    
    /**
     * 发送卫生费催缴提醒
     * @param billId 账单ID
     * @param remindType 提醒方式
     * @return 是否发送成功，异常时返回false
     */
    boolean sendSanitationReminder(Long billId, String remindType);
    
    /**
     * 批量发送卫生费催缴提醒
     * @param communityId 社区ID
     * @param remindType 提醒方式
     * @return 发送结果统计，异常时返回空Map
     */
    Map<String, Integer> batchSendSanitationReminder(Long communityId, String remindType);
    
    /**
     * 获取卫生费统计信息
     * @param communityId 社区ID
     * @param year 年份
     * @return 统计信息，异常时返回空Map
     */
    Map<String, Object> getSanitationFeeStatistics(Long communityId, Integer year);
    
    /**
     * 查询逾期卫生费账单
     * @param communityId 社区ID
     * @return 逾期账单列表，异常时返回空列表
     */
    List<SanitationFee> getOverdueSanitationFees(Long communityId);
    
    /**
     * 计算卫生费金额（按人数、面积等计算）
     * @param householdId 房户ID
     * @param perPersonFee 人均费用
     * @return 计算后的费用金额，异常时返回BigDecimal.ZERO
     */
    BigDecimal calculateSanitationFee(Long householdId, BigDecimal perPersonFee);

    /**
     * 生成卫生费账单（支持计费月份时间段，根据计费方式自动计算）
     * @param communityId 社区ID
     * @param billingMonthRange 计费月份时间段
     * @param dueDate 到期日期
     * @param remark 备注
     * @return 生成的账单数量，异常时返回0
     */
    int generateSanitationFeeByRange(Long communityId, List<String> billingMonthRange,
                                    String dueDate, String remark);
    
    // ==================== 移动端专用方法 ====================
    
    /**
     * 查询当前用户的卫生费账单（App端专用）
     * 
     * 严格按照《Java后端SpringBoot代码开发规范.md》Service规范：
     * - 生产环境标准：移除throws Exception声明，实现优雅降级
     * - 缓存策略：查询方法使用@Cacheable
     * - 性能监控：详细的性能指标记录
     * - 异常处理：统一异常处理机制，返回默认值而不是抛出异常
     * - 参数验证：完善的参数验证机制
     * 
     * 数据权限：判断当前登录用户是否为此房户的业主
     * 
     * @param current 当前页
     * @param size 每页大小
     * @param paymentStatus 缴费状态
     * @param billingPeriod 计费周期
     * @return 分页查询结果，异常时返回空分页结果
     */
    PageResult<SanitationFeeVO> getMySanitationFees(Integer current, Integer size, 
                                                   Integer paymentStatus, String billingPeriod);
    
    /**
     * 获取卫生费详情（App端专用）
     * 
     * 严格按照《Java后端SpringBoot代码开发规范.md》Service规范：
     * - 生产环境标准：移除throws Exception声明，实现优雅降级
     * - 缓存策略：查询方法使用@Cacheable
     * - 性能监控：详细的性能指标记录
     * - 异常处理：统一异常处理机制，返回默认值而不是抛出异常
     * - 参数验证：完善的参数验证机制
     * 
     * 数据权限：判断当前登录用户是否为此房户的业主
     * 
     * @param billId 账单ID
     * @param userId 用户ID
     * @return 账单详情，异常时返回null
     */
    SanitationFeeVO getSanitationFeeDetailForMobile(Long billId, Long userId);
    
    /**
     * 验证用户权限（App端专用）
     * 
     * 验证当前用户是否为该房户的业主，确保数据安全
     * 
     * @param feeId 费用ID
     * @param userId 用户ID
     * @throws BusinessException 权限验证失败时抛出业务异常
     */
    void validateUserPermissionForFee(Long feeId, Long userId);
    
    /**
     * 根据房户ID获取卫生费账单列表
     * 
     * 严格按照《Java后端SpringBoot代码开发规范.md》Service规范：
     * - 生产环境标准：移除throws Exception声明，实现优雅降级
     * - 缓存策略：查询方法使用@Cacheable
     * - 性能监控：详细的性能指标记录
     * - 异常处理：统一异常处理机制，返回默认值而不是抛出异常
     * - 参数验证：完善的参数验证机制
     * 
     * @param householdId 房户ID
     * @param current 当前页
     * @param size 每页大小
     * @return 分页查询结果，异常时返回空分页结果
     */
    PageResult<SanitationFeeVO> getHouseholdSanitationFees(Long householdId, Integer current, Integer size);
} 